feat(advisor): the applies_to axis — evaluate a capability's precondition, never weaken its binding - #48

…dition, never weaken its binding

Three independent audit rounds on 2026-08-23 hit the same defect from both sides, and
the third one ruled out the obvious fix.

THE FALSE POSITIVE. `frontend-verifier` was offered at `repo-audit:phase-2` and
`repo-audit:dimension-4` on two repositories with no application UI at all. Its own
binding reason is CONDITIONAL — "dimension 4 uses the ux-review-overlay WHEN OBSERVABLE
SURFACES EXIST" — and the condition lived in prose nothing read.

THE MIRROR-IMAGE FALSE NEGATIVE. `capability:reference-sync-hygiene-test-gate` was
filtered out as not-applicable during an audit OF SYNC HYGIENE. Both rounds diagnosed
one cause: the capability is scoped to the Orchestrator's own runtime while the audit
target is another repo. `repo-audit:dimension-8` is the clearest case — four
well-chosen capabilities whose concepts transferred and whose INSTRUMENTS did not,
eleven declines across the three rounds, all of that one shape.

AND THE REFUTATION, which is why this annotates instead of suppressing. On a third repo,
one that does have a display surface, `frontend-verifier` was READY on its first
`--doctor` call and produced the finding with the highest evidence-to-effort ratio of
that audit — a provenance banner promising "every number below was measured on your Mac"
three lines above fabricated grant scope, which the code-reading path had missed. Its
propensity moved off the floor onto real positive evidence. So the axis CHANGES NO ORDER
AND NO MEMBERSHIP: a selftest asserts the returned list is identical, in membership and
in order, with the axis populated and emptied, and asserts directly that the
precondition-failing capability keeps first place.

DEDUP (CLAUDE.md §0, checked against the tip). `_annotate_contraindications` +
`repo_knowledge.contraindications_for` landed on main in #38 and already annotate a
candidate a repository's own record says does not work there. This is deliberately NOT a
second copy. A contraindication is a RECORDED per-(repo, capability) judgement — "broken
against THIS app" — and ranks last, because a recorded judgement is high-confidence. A
precondition is an INTRINSIC per-capability declaration evaluated per consult, and only
annotates. `switch-review` is Orchestrator-scoped for every audited repo, so expressing
it as a contraindication would need a hand-written note in all thirteen repo records: an
N x M table nobody maintains. And the Workflows false positive happened BECAUSE no note
existed — a mechanism requiring someone to have written one cannot catch the case where
nobody did. A capability can be both, and the selftest pins that both reach the caller.

THE CHECK IS BUILT, not just declared. `detect_observable_surface` is a bounded,
deterministic probe that returns the markers it matched, so a verdict is evidence that
can be argued with rather than a heuristic's bare boolean. Validated against the three
repositories the audits actually ran on: FALSE for the two with no application UI (and
for this repository), TRUE for the Streamlit SPA and for the one with
`src/fine_art_archive/ui/index.html` — exactly the two negative and one positive
observation on record. `docs/` and `site/` are excluded deliberately; counting a
generated API-docs tree is what would turn the probe back into the false positive.

Verdicts are three-valued. Undeclared, an unnamed repository, and a repo fact whose
checkout was not supplied are all NOT EVALUATED, never failures — collapsing them into
False would silently reclassify all 43 capabilities, and into True would restore the
original defect. An unevaluated precondition NAMES its missing input (`repo_path`),
because a condition nothing can even attempt to check is what this replaces.

`advise()` gains `repo_path`, and the pre-existing MCP schema guard caught it
immediately — proving itself before I could forget. That guard now also reads the
handler's AST, so every caller-settable field is asserted FORWARDED and not merely
advertised.

`evaluate_precondition` hands back `suggested_decline_kind: "precondition_unmet"`, the
kind `capability_propensity.DECLINE_KINDS` marks NON-demotable, so the two halves cannot
disagree: an axis that explained a mismatch while the ledger quietly demoted the binding
for it would be the forbidden correction taking the long way round.

Break->revert, all confirmed to fail without the fix: a failed precondition sinks the
entry; folded into the existing sort key; drops the entry; suggests a demotable decline
kind; suppresses the recorded contraindication; keeps the contraindication reason
JSON-only; an unnamed repository treated as `self`; `both` treated as a mismatch;
undeclared treated as a mismatch; no-checkout conflated with no-surface; `docs/` counted
as an application surface. Two attempts did NOT discriminate and were rewritten: the
first invariance fixture used a capability that was already last alphabetically, and the
first shadowing break was unreachable given the annotation order (stated in a comment
instead, since an assertion that cannot fail is decoration).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>